Crate crokey

Crokey helps incorporate configurable keybindings in crossterm based terminal applications by providing functions

• parsing key combinations from strings
• describing key combinations in strings
• parsing key combinations at compile time
• combining Crossterm key events in key combinations

The KeyCombination

A KeyCombination is made of 1 to 3 “normal” keys with some optional modifiers (alt, shift, ctrl).

It can be parsed, ergonomically built with the key! macro, obtained from key events.

The Combiner

With a Combiner, you can change raw Crossterm key events into key combinations.

When the terminal is modern enough and supports the Kitty protocol, complex combinations with up to three non-modifier keys may be formed, for example Ctrl-Alt-Shift-g-y or i-u.

For standard ANSI terminals, only regular combinations are available, like Shift-o, Ctrl-Alt-Shift-g or i.

The combiner works in both cases: if you presses the ctrl, i, and u keys at the same time, it will result in one combination (ctrl-i-u) on a kitty-compatible terminal, and as a sequence of 2 key combinations (ctrl-i then ctrl-u assuming you started pressing the i before the u) in other terminals.

The print_key example shows how to use the combiner.

let fmt = KeyCombinationFormat::default();
let mut combiner = Combiner::default();
let combines = combiner.enable_combining().unwrap();
if combines {
    println!("Your terminal supports combining keys");
} else {
    println!("Your terminal doesn't support combining non-modifier keys");
}
println!("Type any key combination");
loop {
    terminal::enable_raw_mode().unwrap();
    let e = read();
    terminal::disable_raw_mode().unwrap();
    match e {
        Ok(Event::Key(key_event)) => {
            if let Some(key_combination) = combiner.transform(key_event) {
                match key_combination {
                    key!(ctrl-c) | key!(ctrl-q) => {
                        println!("quitting");
                        break;
                    }
                    _ => {
                        println!("You typed {}", fmt.to_string(key_combination));
                    }
                }
            }
        },
        _ => {}
    }
}

Parse a string

Those strings are usually provided by a configuration file.

use crossterm::event::{KeyCode, KeyEvent, KeyModifiers};
assert_eq!(
    crokey::parse("alt-enter").unwrap(),
    KeyEvent::new(KeyCode::Enter, KeyModifiers::ALT).into(),
);
assert_eq!(
    crokey::parse("shift-F6").unwrap(),
    KeyEvent::new(KeyCode::F(6), KeyModifiers::SHIFT).into(),
);

Use key event “literals” thanks to procedural macros

Those key events are parsed at compile time and have zero runtime cost.

They’re efficient and convenient for matching events or defining hardcoded keybindings.

let fmt = KeyCombinationFormat::default();
match key_event {
    key!(ctrl-c) => {
        println!("Arg! You savagely killed me with a {}", fmt.to_string(key_event).red());
        break;
    }
    key!(ctrl-q) => {
        println!("You typed {} which gracefully quits", fmt.to_string(key_event).green());
        break;
    }
    _ => {
        println!("You typed {}", fmt.to_string(key_event).blue());
    }
}

Complete example in /examples/print_key

Display a string with a configurable format

use crokey::*;
use crossterm::event::{KeyCode, KeyEvent, KeyModifiers};

// The default format
let format = KeyCombinationFormat::default();
assert_eq!(format.to_string(key!(shift-a)), "Shift-a");
assert_eq!(format.to_string(key!(ctrl-c)), "Ctrl-c");

// A more compact format
let format = KeyCombinationFormat::default()
    .with_implicit_shift()
    .with_control("^");
assert_eq!(format.to_string(key!(shift-a)), "A");
assert_eq!(format.to_string(key!(ctrl-c)), "^c");

Deserialize keybindings using Serde

With the “serde” feature enabled, you can read configuration files in a direct way:

use {
    crokey::*,
    crossterm::event::KeyEvent,
    serde::Deserialize,
    std::collections::HashMap,
};
#[derive(Debug, Deserialize)]
struct Config {
    keybindings: HashMap<KeyCombination, String>,
}
static CONFIG_HJSON: &str = r#"
{
    keybindings: {
        a: aardvark
        shift-b: babirussa
        ctrl-k: koala
        alt-j: jaguar
    }
}
"#;
let config: Config = deser_hjson::from_str(CONFIG_HJSON).unwrap();
let key: KeyCombination = key!(shift-b);
assert_eq!(
    config.keybindings.get(&key).unwrap(),
    "babirussa",
);

Instead of Hjson, you can use any Serde compatible format such as JSON or TOML.

Re-exports

• pub use crossterm;

Macros

• key
  check and expand at compile-time the provided expression into a valid KeyCombination.

Structs

• Combiner
  Consumes key events and combines them into key combinations.
• FormattedKeyCombination
• KeyCombination
  A Key combination wraps from one to three standard keys with optional modifiers (ctrl, alt, shift).
• KeyCombinationFormat
  A formatter to produce key combinations descriptions.
• ParseKeyError

Enums

• OneToThree
  An ordered set of 1, 2 or 3 elements, allowing pattern matching.

Statics

• STANDARD_FORMAT
  A lazy initialized KeyCombinationFormat which can be considered as standard and which is used in the Display implementation of the KeyCombination type.

Functions

• as_letter
  Return the raw char if the crossterm key event is a letter event.
• is_key_simple
  For the purpose of key combination, we consider that a key is “simple” when it’s neither a modifier (ctrl,alt,shift) nor a space.
• parse
  parse a string as a keyboard key combination definition.
• parse_key_code
• pop_keyboard_enhancement_flags
  Restore the “normal” state of the terminal. This is done automatically by the combiner on drop, so you should usually not need to call this function.
• push_keyboard_enhancement_flags
  Change the state of the terminal to enable combining keys. This is done automatically by Combiner::enable_combining so you should usually not need to call this function.